Skip Headers

Oracle® XML Developer's Kit Programmer's Guide 10g Release 2 (10.2) Part Number B14252-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 2 Getting Started with Java XDK Components

This chapter contains these topics:

- Installing Java XDK Components

- Java XDK Component Dependencies

- Setting Java XDK Environment Variables for UNIX

- Setting Java XDK Environment Variables for Windows

- Verifying the Java XDK Components Version

## Installing Java XDK Components

The Java XDK components are included with Oracle Database. This chapter assumes that you have installed XDK with Oracle Database and also installed the demo programs on the Oracle Database Companion CD. Refer to "Installing the XDK" for installation instructions and a description of the XDK directory structure.

Example 2-1 shows the UNIX directory structure for the XDK demos and the libraries used by the XDK components. The `$ORACLE_HOME/xdk/demo/java` subdirectories contain sample programs and data files for the XDK for Java components. The chapters in Part I, "XDK for Java" explain how to understand and use these programs.

Example 2-1 Java XDK Libraries, Utilities, and Demos

    - Oracle_home_directory
        | - bin/
             orajaxb
             orapipe
             oraxml
             oraxsl
             transx
        | - lib/
             classgen.jar
             jdev-rt.zip
             oraclexsql.jar
             transx.zip
             xml.jar
             xml.jar
             xmlcomp.jar
             xmlcomp2.jar
             xmldemo.jar
             xmlmesg.jar
             xmlparserv2.jar
             xschema.jar
             xsqlserializers.jar
             xsu12.jar
        | - jlib/
             classes12.jar
             orai18n.jar
             orai18n-collation.jar
             orai18n-mapping.jar
             orai18n-utility.jar
        | - jdbc/
             | - lib/
                  ojdbc14.jar
        | - rdbms/
             | - jlib/
                  xdb.jar

    | - xdk/
             | demo/
                | - java/
                     | - classgen/
                     | - jaxb/
                     | - parser/
                     | - pipeline/
                     | - schema/
                     | - transviewer/
                     | - tranxs/
                     | - xsql/
                     | - xsu/

The subdirectories contain sample programs and data files for the Java XDK components. The chapters in Part I, "XDK for Java" explain how to use these programs to gain an understanding of the most important Java features.

## Java XDK Component Dependencies

The Java XDK components are certified and supported with JDK versions 1.2, 1.3, and 1.4. Figure 2-1 shows the dependencies of Java XDK components when using JDK 1.2 and higher.

Figure 2-1 Java XDK Component Dependencies for JDK 1.2 and Higher

Description of the illustration adxdk110.gif

The Java XDK components require the libraries alphabetically listed in Table 2-1. Note that some of the libraries are not specific to the XDK, but are shared among other Oracle Database components.

Table 2-1 Java Libraries for XDK Components

Library | Directory | Includes . . .
--- | --- | ---
`classes12.jar` | `$ORACLE_HOME/jdbc/lib` | Oracle JDBC drivers for Java 1.2 and 1.3. This JAR depends on `orai18n.jar` for character set support if you use a multibyte character set other than UTF-8, ISO8859-1, or JA16SJIS.
`classgen.jar` | `$ORACLE_HOME/lib` | XML class generator for Java runtime classes. Note: This library is maintained for backward compatibility only. You should use the JAXB class generator in `xml.jar` instead.
`jdev-rt.zip` | `$ORACLE_HOME/lib` | Java GUI libraries for use when working with the demos with the JDeveloper IDE.
`ojdbc14.jar` | `$ORACLE_HOME/jdbc/lib` | Oracle JDBC drivers for Java 1.4. This JAR depends on `orai18n.jar` for character set support if you use a multibyte character set other than UTF-8, ISO8859-1, or JA16SJIS.
`oraclexsql.jar` | `$ORACLE_HOME/lib` | Most of the XSQL Servlet classes needed to construct XSQL pages. Note: This archive is superseded by `xml.jar` and is maintained for backward compatibility only.
`orai18n.jar` | `$ORACLE_HOME/jlib` | Globalization support for JDK 1.2 and later. It is a wrapper of all other Globalization jars and includes character set converters. If you use a multibyte character set other than UTF-8, ISO8859-1, or JA16SJIS, then place this archive in your `CLASSPATH` so that JDBC can convert the character set of the input file to the database character set when loading XML files with XSU, TransX Utility, or XSQL Servlet.
`orai18n-collation.jar` | `$ORACLE_HOME/jlib` | Globalization collation features: the `OraCollator` class and the `lx3*.glb` and `lx4001[0-9].glb` files.
`orai18n-mapping.jar` | `$ORACLE_HOME/jlib` | Globalization locale and character set name mappings: the `OraResourceBundle` class and `lx4000[0-9].glb` files. This archive is mainly used by the products that need only locale name mapping tables.
`orai18n-utility.jar` | `$ORACLE_HOME/jlib` | Globalization locale objects: the `OraLocaleInfo` class, the `OraNumberFormat` and `OraDateFormat` classes, and the `lx[01]*.glb` files.
`transx.zip` | `$ORACLE_HOME/lib` | TransX Utility classes. Note: This archive is replaced by `xml.jar` and is retained for backward compatibility only.
`xdb.jar` | `$ORACLE_HOME/rdbms/jlib` | Classes needed by `xml.jar` and `xmlcomp2.jar` to access `XMLType`. It also includes classes needed to access the XML DB Repository as well as the `XMLType` DOM classes for manipulation of the DOM tree.
`xml.jar` | `$ORACLE_HOME/lib` | Classes from the following libraries: `oraclexsql.jar` `xsqlserializers.jar` `xmlcomp.jar` `xmlcomp2.jar` `transx.jar` The archive also contains the JAXB and Pipeline Processor classes.
`xmlcomp.jar` | `$ORACLE_HOME/lib` | XML JavaBeans that do not depend on the database: `DOMBuilder`, `XSLTransformer`, `DBAccess`, `XSDValidator`, and `XMLDiffer`. Note: This archive is included for backward compatibility only because its classes are included in `xml.jar`. They do not include the visuals Beans included in previous releases.
`xmlcomp2.jar` | `$ORACLE_HOME/lib` | XML JavaBeans that depend on the database: `XMLDBAccess` and `XMLCompress`. Thus, it depends on `xdb.jar`, which includes the classes that support XML DB. Note: This JAR is included for backward compatibility only because its classes are included in `xml.jar`. They do not include the visuals Beans included in previous releases.
`xmldemo.jar` | `$ORACLE_HOME/lib` | The visual JavaBeans: `XMLTreeView`, `XMLTransformPanel`, `XMLSourceView`, and `DBViewer`.
`xmlmesg.jar` | `$ORACLE_HOME/lib` | Needed if you use XML parser with a language other than English.
`xmlparserv2.jar` | `$ORACLE_HOME/lib` | APIs for the following: DOM and SAX parsers XML Schema processor XSLT processor XML compression JAXP Utility functionality such as `XMLSAXSerializer` and asynchronous DOM Builder This library includes `xschema.jar`.
`xschema.jar` | `$ORACLE_HOME/lib` | Includes the XML Schema classes contained in `xmlparserv2.jar`. Note: This JAR file is maintained for backward compatibility only.
`xsqlserializers.jar` | `$ORACLE_HOME/lib` | Serializer classes for XSQL Servlet needed for serialized output such as PDF. Note: This archive is superseded by `xml.jar` and is maintained for backward compatibility only.
`xsu12.jar` | `$ORACLE_HOME/lib` | Classes that implement XSU. These classes have a dependency on `xdb.jar` for `XMLType` access.

See Also: Oracle Database Globalization Support Guide to learn about the Globalization Support libraries Oracle Database JDBC Developer's Guide and Reference to learn about the JDBC libraries Oracle XML DB Developer's Guide to learn about XML DB

## Setting Up the Java XDK Environment

In the Oracle Database installation of the XDK, you must manually set the `$CLASSPATH` (UNIX) or `%CLASSPATH%` (Windows) environment variables. Alternatively, set the `-classpath` option when compiling and running Java programs at the command line.

This section contains the following topics:

- Setting Java XDK Environment Variables for UNIX

- Setting Java XDK Environment Variables for Windows

### Setting Java XDK Environment Variables for UNIX

Table 2-2 describes the UNIX environment variables required for use with the Java XDK components.

Table 2-2 UNIX Environment Settings for Java XDK Components

Variable | Description
--- | ---
`$CLASSPATH` | Includes the following (note that a single period "." to represent the current directory is not required but may be useful):
    .:${CLASSPATHJ}:${ORACLE_HOME}/lib/xmlparserv2.jar:
    ${ORACLE_HOME}/lib/xsu12.jar:${ORACLE_HOME}/lib/xml.jar
`$CLASSPATHJ` | For JDK 1.2 and 1.3, set as follows:
    CLASSPATHJ=${ORACLE_HOME}/jdbc/lib/classes12.jar:
    ${ORACLE_HOME}/jlib/orai18n.jar
For JDK 1.4, set as follows:
    CLASSPATHJ=${ORACLE_HOME}/jdbc/lib/ojdbc.jar:${ORACLE_HOME}/jlib/orai18n.jar
The `orai18n.jar` is needed to support certain character sets.
`$JAVA_HOME` | Installation directory for the Java JDK, Standard Edition. Modify the path that links to the Java SDK.
`$LD_LIBRARY_PATH` | For OCI JDBC connections:
    ${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}
`$PATH` | `${JAVA_HOME}/bin`

#### Testing the Java XDK Environment on UNIX

Table 2-3 describes the command-line utilities included in the Java XDK on UNIX. Before you can use these utilities, you must set up your environment.

Table 2-3 Java XDK Utilities

Executable/Class | Directory/JAR | Description
--- | --- | ---
`xsql` | `$ORACLE_HOME/bin` | XSQL command-line utility. The script executes the `oracle.xml.xsql.XSQLCommandLine` class. Edit this shell script for your environment before use. See Also: "Using the XSQL Pages Command-Line Utility"
`OracleXML` | `$ORACLE_HOME/lib/xsu12.jar` | XSU command-line utility See Also: "Using the XSU Command-Line Utility"
`orajaxb` | `$ORACLE_HOME/bin` | JAXB command-line utility See Also: "Using the JAXB Class Generator Command-Line Utility"
`orapipe` | `$ORACLE_HOME/bin` | Pipeline command-line utility See Also: "Using the XML Pipeline Processor Command-Line Utility"
`oraxml` | `$ORACLE_HOME/bin` | XML parser command-line utility See Also: "Using the XML Parser Command-Line Utility"
`oraxsl` | `$ORACLE_HOME/bin` | XSLT processor command-line utility See Also: "Using the XSLT Processor Command-Line Utility"
`transx` | `$ORACLE_HOME/bin` | TransX command-line utility See Also: "Using the TransX Command-Line Utility"

If your environment is set up correctly, then the UNIX shell script shown in Example 2-2 should generate version and usage information for the utilities.

Example 2-2 Testing the Java XDK Environment on UNIX

    #!/usr/bin/tcsh
    echo;echo "BEGIN TESTING";echo
    echo;echo "now testing the XSQL utility...";echo
    xsql
    echo; echo "now testing the XSU utility...";echo
    java OracleXML
    echo;echo "now testing the JAXB utility...";echo
    orajaxb -version
    echo;echo "now testing the Pipeline utility...";echo
    orapipe -version
    echo;echo "now testing the XSLT Processor utility...";echo
    oraxsl
    echo;echo "now testing the TransX utility...";echo
    transx
    echo;echo "END TESTING"

### Setting Java XDK Environment Variables for Windows

Table 2-4 describes the Windows environment variables required for use with the Java XDK components.

Table 2-4 Windows Environment Settings for Java XDK Components

Variable | Notes
--- | ---
`%CLASSPATH%` | Includes the following (note that a single period "." to represent the current directory is not required but may be useful):
    .;%CLASSPATHJ%;%ORACLE_HOME%\lib\xmlparserv2.jar;
    %ORACLE_HOME%\lib\xsu12.jar;%ORACLE_HOME%\lib\xml.jar;
    %ORACLE_HOME%\lib\xmlmesg.jar;%ORACLE_HOME%\lib\oraclexsql.jar
`%CLASSPATHJ%` | For JDK 1.2 and 1.3, set as follows:
    CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\classes12.jar;%ORACLE_HOME%\jlib\orai18n.jar
For JDK 1.4, set as follows:
    CLASSPATHJ=%ORACLE_HOME%\jdbc\lib\ojdbc.jar;%ORACLE_HOME%\jlib\orai18n.jar
The `orai18n.jar` is needed to support certain character sets.
`%JAVA_HOME%` | Installation directory for the Java SDK, Standard Edition. Modify the path that links to the Java SDK.
`%PATH%` | `%JAVA_HOME%\bin`

#### Testing the Java XDK Environment on Windows

Table 2-3 describes the command-line utilities included in the Java XDK on Windows. Before you can use these utilities, you must set up your environment.

Table 2-5 Java XDK Utilities

Batch File/Class | Directory/JAR | Description
--- | --- | ---
`xsql.bat` | `%ORACLE_HOME%\bin` | XSQL command-line utility. The batch file executes the `oracle.xml.xsql.XSQLCommandLine` class. Edit the batch file for your environment before use. See Also: "Using the XSQL Pages Command-Line Utility"
`OracleXML` | `%ORACLE_HOME%\lib\xsu12.jar` | XSU command-line utility See Also: "Using the XSU Command-Line Utility"
`orajaxb.bat` | `%ORACLE_HOME%\bin` | JAXB command-line utility See Also: "Using the JAXB Class Generator Command-Line Utility"
`orapipe.bat` | `%ORACLE_HOME%\bin` | Pipeline command-line utility See Also: "Using the XML Pipeline Processor Command-Line Utility"
`oraxml.bat` | `%ORACLE_HOME%\bin` | XML parser command-line utility See Also: "Using the XML Parser Command-Line Utility"
`oraxsl.bat` | `%ORACLE_HOME%\bin` | XSLT processor command-line utility See Also: "Using the XSLT Processor Command-Line Utility"
`transx.bat` | `%ORACLE_HOME%\bin` | TransX command-line utility See Also: "Using the TransX Command-Line Utility"

If your environment is set up correctly, then you can run the commands in Example 2-3 at the system prompt to generate version and usage information for the utilities.

Example 2-3 Testing the Java XDK Environment on Windows

    xsql.bat
    java OracleXML
    orajaxb.bat -version
    orapipe.bat -version
    oraxsl.bat
    transx.bat

## Verifying the Java XDK Components Version

To obtain the version of XDK you are working with, use `javac` to compile the Java code shown in Example 2-4.

Example 2-4 XDKVersion.java

    //
    // XDKVersion.java
    //
    import java.net.URL;
    import oracle.xml.parser.v2.XMLParser;
    public class XDKVersion
    {
       static public void main(String[] argv)
       {
          System.out.println("You are using version: ");
          System.out.println(XMLParser.getReleaseVersion());
       }
    }

After compiling the source file with `javac`, run the program on the operating system command line as follows:

    java XDKVersion